TABLE OF CONTENTS

Introduction

The DerbySoft API provides a comprehensive suite of post-booking operations, allowing sellers to manage orders after they have been confirmed and ticketed. Our system supports modifications across four key scenarios:


  • Change Flight Time: Modify the scheduled departure and/or arrival time for an existing itinerary. This operation is performed at the trip level, allowing you to change the onward trip, the return trip, or the entire itinerary. It does not support changing individual flight segments independently.
  • Refund: Initiate full or partial refunds for a ticketed order based on the applicable fare rules.
  • Update Passenger Name: Correct or change passenger names on a booking, typically for minor corrections (e.g., spelling errors).
  • Add Ancillaries:  Purchase additional services like baggage, seats, or meals for an existing order.

The support level for each operation type (e.g., fully automated, manual process) varies by supplier and is detailed in the technicalCapabilities section of the order response. The following sections describe the endpoints and workflows for initiating and tracking these post-booking modifications.


Change Flight Time

This section outlines the high-level workflow for changing the flight time on an existing booking. The process involves a sequence of API calls to explore options, calculate new pricing, and finally confirm the change.

The typical flow is as follows:

  • Step1: Retrieve Order Details (orderRetrieve)
    • First, fetch the latest details of the existing order to understand its current state
  • Step 2: Search for Alternative Flights (orderReshop)
    • Use this operation to search for and retrieve available alternative flights that meet the new travel requirements. This provides a list of new onward and/or return trip options.
  • Step 3: Request a Revised Price (orderReshopReprice)
    • After selecting a preferred new flight from the options, call this endpoint to get a detailed and accurate revised price for the change. The response will include a new total amount, balance due amount, and a breakdown of new fares and taxes.
  • Step 4: Submit the Change Request (orderChange)
    • Once the customer agrees to the new price, use this endpoint to formally submit the change request. This call typically includes payment information for any additional amount due.
  • Step 5: Check Change Status
    • The result of the asynchronous change operation can be monitored in two ways:
      • Polling: Call orderRetrieve periodically; the response will reflect the updated itinerary once the change is processed and will contain a modification history.
      • Webhook Notification: Subscribe to push notifications to receive an instant update on the status of the change request (e.g., confirmed, confirm failed) without the need for polling.


Refund

This section outlines the high-level workflow for submitting a refund request for an existing ticket. The API supports two distinct flows, depending on whether you need to check the estimated refund amount before proceeding.


Flow 1: Direct Refund

This is a straightforward process for immediately submitting a refund request: 

  • Step 1: Retrieve Order Details (orderRetrieve)
    • Fetch the latest order details
  • Step 2: Submit Refund Request (orderChange)
    • Initiate the refund process directly. The final refundable amount and result are determined by the supplier during processing.
  • Step 3: Check Refund Status & Amount: 
    • The final result—including the approved refund amount and status— can be retrieved by:
      • Polling: Calling the orderRetrieve operation to find the updated refund status in the order details.
      • Webhook Notification: Receiving a push notification with the outcome once processing is complete.


Flow 2: Refund with Estimate

This two-step process allows you to check the estimated refund amount before formally submitting the request:

Note: The Refund with Estimate flow (which would involve a preliminary request to the airline for a refund calculation before formal submission) is currently under development and is not yet supported.

  • Step 1: Retrieve Order Details (orderRetrieve)
    • Fetch the latest order details
  • Step 2: Get Refund Estimate (refundEstimate)
    •  Request a preliminary calculation of the refundable amount from suppliers
  • Step 3: Submit Refund Request (orderChange)
    • After reviewing the estimate, formally submit the refund request.
  • Step 4: Check Refund Status & Amount
    • The final result—including the approved refund amount and status— can be retrieved by:
      • Polling: Calling the orderRetrieve operation to find the updated refund status in the order details.
      • Webhook Notification: Receiving a push notification with the outcome once processing is complete.



Update Passenger Name

This section outlines the high-level workflow for updating passenger name details on an existing booking. The process allows for corrections or modifications to passenger names after a booking has been confirmed.

  • Step 1: Retrieve Order Details (orderRetrieve)
    • First, fetch the latest details of the order to confirm its current status and review the existing passenger information.
  • Step 2: Submit Name Change Request (orderChange)
    • Initiate the name modification process by submitting the necessary corrections or updates to the passenger details.
  • Step 3: Check Name Change Status
    • The result of the name update request is delivered asynchronously and can be monitored through:
      • Polling: Calling the orderRetrieve operation periodically, the response will reflect the updated passenger information once the change is successfully processed.
      • Webhook Notification: Receiving a push notification with the final outcome of the name change request.
Note: Name changes are typically subject to airline policies and may be limited to minor corrections (e.g., spelling errors). Significant name changes may not be permitted by some carriers. The success of the request depends entirely on the airline's validation and approval.


Add Ancillaries

This section outlines the high-level workflow for adding ancillary services to an existing confirmed booking. This process allows you to purchase additional services for an existing order after the initial ticket has been issued.

  • Step 1: Retrieve Order Details (orderRetrieve)
    • First, fetch the latest details of the order to confirm its current status and eligibility for adding ancillary services.
  • Step 2: Check Available Services
    • Query for available ancillary services using two dedicated endpoints:
      • seatAvailability: Retrieve available seat options with precise locations, features, and pricing for the specific flights in the booking.
      • serviceList: Query for other available ancillary services like baggage allowances, meals, sports equipment, or special assistance. 
  • Step 3: Submit Ancillary Purchase Request (orderChange)
    • Initiate the purchase by submitting the selected service(s) along with the necessary payment information for any additional fees.
  • Step 4: Check Purchase Status
    • The result of the ancillary purchase is delivered asynchronously and can be monitored through:
      • Polling: Calling the orderRetrieve operation; the response will include the newly added services in the order details once successfully processed.
      • Webhook Notification: Receiving a push notification with the final outcome of the ancillary purchase request.
Note: The availability and pricing of ancillary services are subject to change based on real-time inventory and airline policies. Successful addition is contingent upon payment authorization and confirmation from the supplier's system.